home *** CD-ROM | disk | FTP | other *** search
/ Night Owl 6 / Night Owl's Shareware - PDSI-006 - Night Owl Corp (1990).iso / 033a / uti215a.zip / SLUTI.DOC < prev    next >
Text File  |  1991-06-15  |  13KB  |  318 lines
  1.  
  2. Searchlight UTI Driver  --  Version 2.15     (For Searchlight BBS 2.15 & Later)
  3.  
  4.  
  5. Introduction
  6.  
  7. Searchlight UTI is a Universal Text Interface driver for Searchlight BBS. 
  8. This version works with Searchlight 2.15 and later (it is not compatible 
  9. with Searchlight 1.x).  
  10.  
  11. A UTI driver is a series of programs that can convert messages between the 
  12. format used by a particular BBS program and a "Universal" format that is 
  13. recognized by various application programs. The specification for UTI was 
  14. developed by Kip Compton for use with his MegaMail offline reader software 
  15. and PCRelay network software. The Searchlight UTI driver allows you to run 
  16. MegaMail, PCRelay and other UTI applications on your Searchlight BBS system.
  17.  
  18. The Searchlight UTI physically consists of seven separate EXE files which 
  19. perform various functions, as described below. These programs are command 
  20. line driven, produce no screen output, and are designed to be called by a 
  21. UTI application (such as MegaMail) rather than directly from DOS or from a 
  22. batch file.  
  23.  
  24.  
  25. Installation
  26.  
  27. The Searchlight UTI driver should be installed simply by copying all the 
  28. executable files into any directory in your system that's part of the 
  29. command search path (so that the programs can be executed from any 
  30. directory).
  31.  
  32. The UTI driver is compatible with single or multinode Searchlight BBS 
  33. systems.
  34.  
  35. UTI driver programs expect to find the CONFIG.SL2 file in the current 
  36. directory when run. The UTI programs will also recognize an environment 
  37. variable, SLBBS, which should be set equal to the directory where the 
  38. Searchlight CONFIG.SL2 file is located. For example:
  39.  
  40.       SET SLBBS=C:\BBS\NODE1
  41.  
  42. If this environment variable is set, the UTI programs will look for the 
  43. CONFIG file in C:\BBS\NODE1, unless a CONFIG.SL2 file exists in the current 
  44. directory, in which case it will be used instead.
  45.  
  46. On multiuser systems, please be sure that when DOORS execute from a particular 
  47. node, and use the UTI driver, that the UTI driver is accessing the CONFIG 
  48. file for that node. If you use the SET SLBBS environment parameter, each DOS
  49. environment in which a Searchlight node runs should have the parameter set 
  50. to point to its own CONFIG.SL2 file. For example, if you run Desqview, you 
  51. would want to SET SLBBS as part of a batch file that launches each SL task, 
  52. rather than in your AUTOEXEC file when booting the system.
  53.  
  54.  
  55.  
  56.                                   Programs
  57.  
  58. Here is a summary of the UTI programs and parameters. Note: in all examples 
  59. except UTILSTRD.EXE, the filename may be omitted. Omitting the filename 
  60. causes the output to go to the console (screen) instead of a text file.
  61.  
  62.  
  63. High Message Number
  64. -------------------
  65. UTIHIGH.EXE <subboard> <filename>
  66.  example: UTIHIGH GENERAL HIGHMSG.TXT
  67.  
  68. This program returns the number of the highest message in a given subboard, 
  69. as a plain text (decimal ASCII) number, to the speicifed output file (or to 
  70. the console if no output file is given).
  71.  
  72.  
  73. Message Export
  74. --------------
  75. UTIEXPRT.EXE <subboard> <startmsg> <filename>
  76.  example: UTIEXPRT SLBBS 245 MESSAGE.TXT
  77.  
  78. The export utility exports all messages from a subboard from the given 
  79. message number to the end of the subboard. The messages are exported to the 
  80. given text file.
  81.  
  82. The <startmsg> need not specify the number of an existing message (if it 
  83. does not, output starts at the next highest message).
  84.  
  85. The format of the output file is the standard UTI format given in the UTI 
  86. specifications (see below for more information).
  87.  
  88.  
  89. Message Import
  90. --------------
  91. UTIIMPRT.EXE <subboard> <filename>
  92.  example: UTIIMPRT MAIL INPUT.TXT
  93.  
  94. The import utility reads the messages in the given file and imports them 
  95. into the specified Searchlight subboard. As shown in this example, you can 
  96. import (and export) private mail by specifying the MAIL subboard.
  97.  
  98. The import file is in the same format as the output file produced by 
  99. UTIEXPRT.EXE.
  100.  
  101.  
  102. Subboard List
  103. -------------
  104. UTILIST.EXE <filename>
  105.  example: UTILIST SUBLIST.TXT
  106.  
  107. Generates a list of subboards.  The list is always output in alphabetical 
  108. order and contains all subboards as defined in the SETUP program.
  109.  
  110. Each entry is 3 plain text lines. Lines 1 and 2 contain the subboard's name 
  111. (one to eight characters). Line 3 contains the subboard's long description.
  112.  
  113.  
  114. Last Read Pointers
  115. ------------------
  116. UTILSTRD.EXE [READ|WRITE] <filename> <username>
  117.  example: UTILSTRD READ LAST.TXT FRANK LAROSA
  118.  example: UTILSTRD WRITE LAST.TXT FRANK LAROSA
  119.  
  120. The READ parameter generates a list of the user's highest message read 
  121. pointers for each subboard in which the user is a member. Subboards in which 
  122. the user is not a member are listed as -1. The output goes into the named 
  123. output file. Subboards are listed in the same order as UTILIST.
  124.  
  125. The WRITE parameter updates the user's last read pointers using the values 
  126. in the named input file, which must be in the same order as the output file.
  127.  
  128. Although Searchlight allows read and write priviledges to be specified 
  129. independently, this is not supported by UTI applications. Therefore, 
  130. UTILSTRD will report a last read value of -1 for any subboard to which a 
  131. user does not have full read/write access.  
  132.  
  133.  
  134. Version
  135. -------
  136. UTIVER.EXE <filename>
  137.  example: UTIVER VERSION.TXT
  138.  
  139. Generates the version number (currently 2) and tag line, to the named output 
  140. file. Version 2 is the version of the UTI specification with which this 
  141. driver is compatible; not the version number of the driver.
  142.  
  143.  
  144. UTI Door File
  145. -------------
  146. UTIDOOR.EXE <filename>
  147.  example: UTIDOOR UTIDOOR.TXT
  148.  
  149. Generates UTI door information into the named output file.  The UTIDOOR 
  150. output file contains five lines in plain text:
  151.  
  152.  Line 1: User name
  153.  Line 2: Actual BPS rate
  154.  Line 3: Com port (0-4)
  155.  Line 4: Locked DTE rate
  156.  Line 5: Time remaining in seconds
  157.  
  158. Note: UTIDOOR is not a UTI driver in the sense that it is not directly 
  159. called by UTI applications. UTIDOOR is normally run as the first command of 
  160. a batch file which executes a UTI application (such as Megamail) in order to 
  161. generate the above file, for use by the application. The standard name for 
  162. this file is UTIDOOR.TXT.
  163.  
  164.  
  165.                                    Notes:
  166.  
  167. Errors
  168. ------
  169. The Searchlight UTI drivers will exit with an error level between 0 and 5 
  170. indicating the result of the program execution. All drivers share a common 
  171. error level list, as follows:
  172.  
  173. Level    Problem & Suggested Action
  174. -----    --------------------------
  175.   0       No error
  176.  
  177.   1       Could not open system files. Either your CONFIG.SL2 file is not
  178.           in the current directory, or the paths it contains are invalid,
  179.           your SLBBS data files are missing or corrupt, or the UTI driver
  180.           could not open the files due to operating system restrictions
  181.           (such as out of file handles).
  182.  
  183.   2       Could not open specified subboard. The subboard name specified
  184.           on the command line is not a valid name, or a DOS error occured
  185.           when attempting to open the files.
  186.  
  187.   3       Could not open input or output file. For input files, this usually
  188.           means the file did not exist. On output, it means that DOS was
  189.           unable to create the file.
  190.  
  191.   4       Error in input file. The format of an input file was not the 
  192.           expected UTI file format.
  193.  
  194.   5       Subboard full. Reported by UTIIMPRT if a subboard is full. To
  195.           correct it, delete messages from the subboard, increase the 
  196.           subboard's maximum message count, or enable auto delete on the
  197.           subboard.
  198.  
  199.  
  200.  
  201. Handling Private Mail
  202. ---------------------
  203. Because of the way personal mail is stored in Searchlight BBS, the UTI 
  204. driver at this time does not support the transfer of private messages via a 
  205. network such as PCRelay. However, private mail transfers to an offline 
  206. reader program are supported.
  207.  
  208. When UTIIMPRT imports messages into a public subboard (ie. any subboard 
  209. other than the MAIL subboard), messages marked as PRIVATE in the message 
  210. header of the UTI import file will be discarded. Since there are no public/ 
  211. private flags on messages in Searchlight public subboards, all messages 
  212. exported from public subboards will have a PUBLIC designation in the UTI 
  213. output file.
  214.  
  215. The MAIL subboard is treated as an exception. UTIIMPRT and UTIEXPRT will 
  216. work in conjunction with the MAIL subboard so as to provide a means of 
  217. importing and exporting private mail for use with offline reader doors. 
  218. UTIIMPRT, when called with the MAIL subboard as a parameter, will import any 
  219. message in the input file (regardless of the PUBLIC/PRIVATE flag) as a 
  220. private Searchlight mail message to the addressee in the message header. If 
  221. the addressee does not have a mailbox in Searchlight, one will be created 
  222. when the message is imported.  
  223.  
  224. UTIEXPRT, when called on the MAIL subboard, always exports only new messages 
  225. addressed to the currently logged on user. UTIEXPRT reads the "times read" 
  226. counter in the message headers to determine which messages are new, and 
  227. ignores the starting message number specified on the command line. The 
  228. "times read" indicator is AUTOMATICALLY incremented whenever a message is 
  229. exported from the MAIL subboard, so that message may not be exported again.
  230.  
  231. Note that the UTILSTRD program will read and write a user's correct high 
  232. message read pointer from the MAIL subboard, although that number will have 
  233. no effect on UTIEXPRT.
  234.  
  235. UTILIST will show the "MAIL" subboard as a regular subboard. When setting up 
  236. a PCRelay network, care must be taken to prevent the application program 
  237. from exporting from or importing to the MAIL subboard.  When setting up an 
  238. offline mail system, users should be allowed to select the MAIL subboard as 
  239. they would any other subboard.  
  240.  
  241.  
  242.  
  243. Textual Considerations
  244. ----------------------
  245. The UTIEXPRT program reformats messages to a maximum column width of 72 
  246. characters, as is required by UTI applications. Quoted text is handled by 
  247. stripping off the initial ">" character and any additional non-textual 
  248. characters, reformatting the paragraph, and adding back the ">" characters.
  249.  
  250. UTIEXPRT exports up to 40 characters for the message subject, although many 
  251. UTI applications limit the subject field to 25. Expect that subject fields 
  252. longer than 25 characters may be truncated by UTI applications.
  253.  
  254. UTIIMPRT does not reformat messages. Expect messages imported by UTIIMPRT to 
  255. have a maximum width of 72 characters.
  256.  
  257. UTIEXPRT removes Searchlight color codes (two-letter codes beginning with a 
  258. backslash) from outgoing messages. No modifications are made to incoming 
  259. messages.  
  260.  
  261. INCLUDE files are not expanded when exporting messages.
  262.  
  263.  
  264.  
  265. UTIRFLAG.EXE
  266. ------------
  267. The Searchlight UTI driver does not include this program, which is defined 
  268. as an optional utility in the UTI specification. Searchlight does not 
  269. require this program since the UTIEXPRT program automatically updates the 
  270. appropriate counter when private messages are exported.
  271.  
  272.  
  273. UTI Import Speed
  274. ----------------
  275. Because importation of new messages is usually the UTI's biggest job in a 
  276. network environment, the speed at which messages are imported is an 
  277. important concern.
  278.  
  279. Message import speed will vary widely according to the speed of the 
  280. computer, content of the messages, and configuration of the message bases.  
  281. Import time will increase if compression is used (but the size of the 
  282. Searchlight message file will decrease). Import time will also increase if 
  283. auto purge of old messages is required during the import.  
  284.  
  285. Suggestions to decrease message import times:
  286.  
  287.   - Place the import file on a different drive than the SLBBS message
  288.     files (use a ram disk if possible). This is highly recommended for
  289.     large import jobs.
  290.  
  291.   - Use disk cache software, allocating all unused RAM to the cache.
  292.  
  293.   - Turn data compression off on the target subboards.
  294.  
  295.  
  296.  
  297. Developing UTI Applications
  298. ---------------------------
  299. Programmers who wish to develop message base applications can call UTI 
  300. programs from their main program in order to simplify the task of reading 
  301. and writing messages from the message bases. Applications that conform 
  302. strictly to UTI specifications will be compatible with any BBS system that 
  303. provides a UTI driver.
  304.  
  305. For more information on UTI file formats and specifications, developers 
  306. should contact:
  307.  
  308.    Kip Compton
  309.    PO Box 206
  310.    MIT Branch
  311.    Cambridge, MA 02139
  312.  
  313.    BBS: 703-690-7361
  314.                     
  315.                                                            -----------------
  316.                                                            Frank LaRosa 5/91
  317.  
  318.